---
id: index
title: Temporal CLI command reference
sidebar_label: Temporal CLI
description: The Temporal CLI offers terminal access to Temporal Services for managing, monitoring, and debugging Workflows and Activities, including Namespace and Task Queue management, with embedded development support.
slug: /cli
toc_max_heading_level: 4
keywords:
  - cli
  - dev server
  - install
  - temporal cli
  - term
tags:
  - Temporal CLI
---

:::tip Support, stability, and dependency info

Temporal CLI 1.1 is now available.
See the [release notes](https://github.com/temporalio/cli/releases/tag/v1.1.0) or view the latest command information from the utility:

```
temporal [command] --help
```

:::

The Temporal CLI provides direct access to a Temporal Service via the terminal.
It's a powerful tool for managing, monitoring, and debugging Temporal Applications.
You can use it to start, stop, inspect and operate on Workflows and Activities, and perform administrative tasks such as Namespace, Schedule, and Task Queue management.

The Temporal CLI also includes an embedded Temporal Service suitable for use in development and CI/CD.
It includes the [Temporal Server](/clusters#temporal-server), SQLite persistence, and the [Temporal Web UI](/web-ui).

:::note

When upgrading from [tctl](/tctl-v1) to the Temporal CLI, make sure to update your environment variables and use updated commands.
For details, see [CLI release notes](https://github.com/temporalio/cli/releases/).

:::

## Install the Temporal CLI {#install}

**How to download and install the Temporal CLI**

The Temporal CLI is available on macOS, Windows, and Linux.

### How to install the Temporal CLI on macOS

Choose one of the following install methods to install the Temporal CLI on macOS:

- Install the Temporal CLI with Homebrew.

```shell
brew install temporal
```

- Install the Temporal CLI from CDN.

  1. Select the platform and architecture needed.

  - Download for Darwin amd64: https://temporal.download/cli/archive/latest?platform=darwin&arch=amd64
  - Download for Darwin arm64: https://temporal.download/cli/archive/latest?platform=darwin&arch=arm64

  2. Extract the downloaded archive.

  3. Add the Temporal CLI binary to your PATH.

### How to install the Temporal CLI on Linux

Choose one of the following install methods to install the Temporal CLI on Linux:

- Install the Temporal CLI from CDN.

  1. Select the platform and architecture needed.

  - Download for Linux amd64: https://temporal.download/cli/archive/latest?platform=linux&arch=amd64
  - Download for Linux arm64: https://temporal.download/cli/archive/latest?platform=linux&arch=arm64

  2. Extract the downloaded archive.

  3. Add the `temporal` binary to your PATH.

### How to install the Temporal CLI on Windows

Choose one of the following methods to install the Temporal CLI on Windows:

- Install the Temporal CLI from CDN.

  1. Select the platform and architecture needed and download the binary.

  - Download for Windows amd64: https://temporal.download/cli/archive/latest?platform=windows&arch=amd64
  - Download for Windows arm64: https://temporal.download/cli/archive/latest?platform=windows&arch=arm64

  2. Extract the downloaded archive.

  3. Add the `temporal.exe` binary to your PATH.

## Command set

- [temporal activity](/cli/activity/)
- [temporal batch](/cli/batch/)
- [temporal env](/cli/env/)
- [temporal operator](/cli/operator/)
- [temporal schedule](/cli/schedule/)
- [temporal server](/cli/server)
- [temporal task-queue](/cli/task-queue/)
- [temporal workflow](/cli/workflow/)

## Configuration

The following information provides important configuration details.

### Namespace registration

Namespaces are pre-registered at startup for immediate use.
Customize pre-registered Namespaces with the following command:

```shell
temporal server start-dev --namespace foo --namespace bar
```

Register Namespaces with `namespace create`:

```shell
temporal operator namespace create --namespace foo
```

### Enable or disable Temporal UI

By default, the Temporal UI is enabled when running the development server using the Temporal CLI.
To disable the UI, use the `--headless` modifier:

```shell
temporal server start-dev --headless
```

### Dynamic configuration

Advanced Temporal CLI configuration requires a dynamic configuration file.

To set values on the command line, use `--dynamic-config-value KEY=JSON_VALUE`.
For example, enable the Search Attribute cache:

```bash
temporal server start-dev --dynamic-config-value system.forceSearchAttributesCacheRefreshOnRead=false
```

This setting makes created Search Attributes immediately available.

## Environment variables

The following table describes the environment variables you can set for the Temporal CLI.

| Variable                                 | Definition                                                                | Client Option                   |
| ---------------------------------------- | ------------------------------------------------------------------------- | ------------------------------- |
| `TEMPORAL_ADDRESS`                       | Host and port (formatted as host:port) for the Temporal Frontend Service. | --address                       |
| `TEMPORAL_CODEC_AUTH`                    | Authorization header for requests to Codec Server.                        | --codec-auth                    |
| `TEMPORAL_CODEC_ENDPOINT`                | Endpoint for remote Codec Server.                                         | --codec-endpoint                |
| `TEMPORAL_NAMESPACE`                     | Namespace in Temporal Workflow. Default: "default".                       | --namespace                     |
| `TEMPORAL_TLS_CA`                        | Path to server CA certificate.                                            | --tls-ca-path                   |
| `TEMPORAL_TLS_CERT`                      | Path to x509 certificate.                                                 | --tls-cert-path                 |
| `TEMPORAL_TLS_DISABLE_HOST_VERIFICATION` | Disables TLS host name verification. Default: false.                      | --tls-disable-host-verification |
| `TEMPORAL_TLS_KEY`                       | Path to private certificate key.                                          | --tls-key-path                  |
| `TEMPORAL_TLS_SERVER_NAME`               | Override for target TLS server name.                                      | --tls-server-name               |

## Proxy support

The Temporal CLI provides support for users who are operating behind a proxy.
This feature ensures seamless communication even in network-restricted environments.

#### Setting up proxy support

If you are behind a proxy, you'll need to instruct the Temporal CLI to route its requests via that proxy.
You can achieve this by setting the `HTTPS_PROXY` environment variable.

```command
export HTTPS_PROXY=<host>:<port>
```

Replace `<host>` with the proxy's hostname or IP address, and `<port>` with the proxy's port number.

Once set, you can run the Temporal CLI commands as you normally would.

:::note

Temporal CLI uses the gRPC library which natively supports HTTP CONNECT proxies. The gRPC library checks for the `HTTPS_PROXY` (and its case-insensitive variants) environment variable to determine if it should route requests through a proxy.

:::

In addition to `HTTPS_PROXY`, gRPC also respects the `NO_PROXY` environment variable.
This can be useful if there are specific addresses or domains you wish to exclude from proxying.

For more information, see [Proxy](https://github.com/grpc/grpc-go/blob/master/Documentation/proxy.md) in the gRPC documentation.

## Auto-completion

Enable auto-completion using the following commands.

### zsh auto-completion

1. Add the following line to your `~/.zshrc` startup script:

   ```sh
   eval "$(temporal completion zsh)"
   ```

2. Re-launch your shell or run:

   ```sh
   source ~/.zshrc
   ```

### Bash auto-completion

1. Install [bash-completion](https://github.com/scop/bash-completion#installation) and add the software to your `~/.bashrc`.

2. Add the following line to your `~/.bashrc` startup script:

   ```sh
   eval "$(temporal completion bash)"
   ```

3. Re-launch your shell or run:

   ```sh
   source ~/.bashrc
   ```

:::note

If auto-completion fails with the error: `bash: _get_comp_words_by_ref: command not found`, you did not successfully install [bash-completion](https://github.com/scop/bash-completion#installation). This package must be loaded into your shell for `temporal` auto-completion to work.

:::

### Fish auto-completion

1. Create the Fish custom completions directory if it does not already exist:

   ```fish
   mkdir -p ~/.config/fish/completions
   ```

2. Configure the completions to load when needed. Note: the file name must be `temporal.fish` or the completions will not be found:

   ```fish
   echo 'eval "$(temporal completion fish)"' >~/.config/fish/completions/temporal.fish
   ```

3. Re-launch your shell or run:

   ```fish
   source ~/.config/fish/completions/temporal.fish
   ```

## Temporal dev server {#start-dev-server}

**How to start the Temporal development server**

To start the Temporal development server run the following command:

```bash
temporal server start-dev
```

This command automatically starts the Web UI, creates the `default` [Namespace](/namespaces), and uses an in-memory database.

The Temporal Server should be available on `localhost:7233` and the Temporal Web UI should be available at [`http://localhost:8233`](http://localhost:8233/).

The in-memory SQLite database does not persist if you stop the dev server.
Use the `--db-filename` option to specify a database file, persisting application state.
This is helpful if you plan on stopping and re-starting the dev server.

```shell
temporal server start-dev --db-filename temporal.db
```

:::note

Local databases created with `--db-filename` may not be compatible with newer versions of the Temporal CLI.
The `temporal server` command is only intended for development environments.

:::

For the full list of dev server options use the `--help` flag:

```shell
temporal server start-dev --help
```

## Common CLI operations {#common-operations}

The following are some of the more common operations you can perform with the Temporal CLI.

### Start a Workflow

In another terminal, use the following commands to interact with the Server.
The following command starts a Workflow:

```shell
$ temporal workflow start \
  --task-queue hello-world \
  --type MyWorkflow \
  --workflow-id 123 \
  --input 456

Running execution:
  WorkflowId                                   123
  RunId       357074e4-0dd8-4c44-8367-d92536dd0943
  Type        MyWorkflow
  Namespace   default
  TaskQueue   hello-world
  Args        [456]
```

Shorthand options are available:

```shell
temporal workflow start --task-queue hello-world --type MyWorkflow --workflow-id 123 --input 456
```

You can also list and describe Workflows:

```shell
$ temporal workflow list

  Status   WorkflowId     Name       StartTime
  Running         123  MyWorkflow  14 seconds ago

$ temporal workflow describe --workflow-id 123

{
  "executionConfig": {
    "taskQueue": {
      "name": "hello-world",
      "kind": "Normal"
    },
    "workflowExecutionTimeout": "0s",
    "workflowRunTimeout": "0s",
    "defaultWorkflowTaskTimeout": "10s"
  },
  "workflowExecutionInfo": {
    "execution": {
      "workflowId": "123",
      "runId": "357074e4-0dd8-4c44-8367-d92536dd0943"
    },
    "type": {
      "name": "MyWorkflow"
    },
    "startTime": "2023-04-15T06:42:31.191137Z",
    "status": "Running",
    "historyLength": "2",
    "executionTime": "2023-04-15T06:42:31.191137Z",
    "memo": {

    },
    "autoResetPoints": {

    },
    "stateTransitionCount": "1"
  },
  "pendingWorkflowTask": {
    "state": "Scheduled",
    "scheduledTime": "2023-04-15T06:42:31.191173Z",
    "originalScheduledTime": "2023-04-15T06:42:31.191173Z",
    "attempt": 1
  }
}
```

For more detailed output in JSON format, use the following command:

```shell
$ temporal workflow list --fields long --output json

[
  {
    "execution": {
      "workflow_id": "123",
      "run_id": "357074e4-0dd8-4c44-8367-d92536dd0943"
    },
    "type": {
      "name": "MyWorkflow"
    },
    "start_time": "2023-04-15T06:42:31.191137Z",
    "status": 1,
    "execution_time": "2023-04-15T06:42:31.191137Z",
    "memo": {},
    "task_queue": "hello-world"
  }
]
```

Filter out Workflows based on Workflow Type with [jq](https://stedolan.github.io/jq/):

```shell
$ temporal workflow list --fields long --output json | jq '.[].type.name'

"OtherWorkflow"
"MyWorkflow"
"MyWorkflow"
```

To count the number of Workflows, use the following command:

```shell
$ temporal workflow list --fields long --output json | jq '.[].type.name' | uniq -c

   1 "OtherWorkflow"
   2 "MyWorkflow"
```

To see the full range of Workflow-related commands, run `temporal workflow` or see the [Temporal CLI workflow command reference](/cli/workflow).

For a full list of available commands, run `temporal` without arguments or see [Available commands](#command-set).

### Customize your environment variables

To communicate with a different Server, like a production Namespace on Temporal Cloud:

1. Create an environment named `prod`.
2. Pass `--env prod` to commands, like `temporal workflow list --env prod`.

To create a new environment and set its properties:

```shell
temporal env set prod.namespace production.f45a2
temporal env set prod.address production.f45a2.tmprl.cloud:7233
temporal env set prod.tls-cert-path /temporal/certs/prod.pem
temporal env set prod.tls-key-path /temporal/certs/prod.key
```

Check your settings:

```shell
$ temporal env get prod

  address        production.f45a2.tmprl.cloud:7233
  namespace      production.f45a2
  tls-cert-path  /temporal/certs/prod.pem
  tls-key-path   /temporal/certs/prod.key
```

Run a command to test the connection:

```shell
$ temporal workflow list --env prod
```

For a full list of properties, use `temporal env set -h`.

```shell
$ temporal env set -h

OPTIONS:
   Client Options:

   --address value                          The host and port (formatted as host:port) for the Temporal Frontend Service. [$TEMPORAL_CLI_ADDRESS]
   --codec-auth value                       Sets the authorization header on requests to the Codec Server. [$TEMPORAL_CLI_CODEC_AUTH]
   --codec-endpoint value                   Endpoint for a remote Codec Server. [$TEMPORAL_CLI_CODEC_ENDPOINT]
   --command-timeout duration               Timeout for the span of a command. (default 0s)
   --env value                              Name of the environment to read environmental variables from. (default: "default")
   --grpc-meta value [ --grpc-meta value ]  Contains gRPC metadata to send with requests (format: key=value). Values must be in a valid JSON format.
   --namespace value, -n value              Identifies a Namespace in the Temporal Workflow. (default: "default") [$TEMPORAL_CLI_NAMESPACE]
   --tls-ca-path value                      Path to server CA certificate. [$TEMPORAL_CLI_TLS_CA]
   --tls-cert-path value                    Path to x509 certificate. [$TEMPORAL_CLI_TLS_CERT]
   --tls-disable-host-verification          Disables TLS host name verification if already enabled. (default: false) [$TEMPORAL_CLI_TLS_DISABLE_HOST_VERIFICATION]
   --tls-key-path value                     Path to private certificate key. [$TEMPORAL_CLI_TLS_KEY]
   --tls-server-name value                  Provides an override for the target TLS server name. [$TEMPORAL_CLI_TLS_SERVER_NAME]

   Display Options:

   --color value  when to use color: auto, always, never. (default: "auto")
```
